[<<Previous Entry]
[^^Up^^]
[Next Entry>>]
[Menu]
[About The Guide]
twBRBrowse( wT, wL, wB, wR, aColumns, cTitle,;
cTopKey, bScopeBlock, lEditFlag,;
aActionKeys, wColor, wSType, wFType,;
wFColor, lScBar, lMsgs, lAlite, nFreeze,;
lStabilize, bPreRun, bPostRun, nExitKey,;
aSeparators, lOKAppend, lSound, lWindow,;
bBarColor, aSrch )
----------------------------------------------------------------------------
twBRBrowse() is a very flexible, completely configurable, mouse
driven database handler. It and twRABrowse() are the central
functions in the TSDWIN browse system. The programmer has complete
control over column definitions and keystroke handling, as with
other TSDWIN browses.
There is built in mouse support, scoping and the ability to pass
executable code to the function through the use of actionkeys. You
may also obtain a reference to the browse and its full cargo
structure, and modify its behaviour on the fly.
The default keystroke handling in twBRBrowse() can be overridden by
assigning ActionKey blocks to replace the defaults. ActionKeys are
processed BEFORE the default keystroke handler. This method was
deemed easier for programmers than the method of passing an entire
ApplyKey function. Both methods will be made available in a
future release. The defaults vary according to the Autolite
setting:
Keystroke Handling:
Up Arrow ---------+
Down Arrow |
Left Arrow |
Right Arrow |
Page Down |- Scroll the Highlight Bar in
Page Up | the normal way.
Ctrl Page Down |
Ctrl Page Up |
Ctrl Left Arrow |
Ctrl Right Arrow |
Ctrl Home |
Ctrl End ---------+
Escape - Exit with no choice.
Enter - If EditFlag is .T., allow editing of
the current field in the current
record, otherwise, exit the browse.
Alpha Keys - Speed Search (See aSrch).
Back Space - Reset Search String to empty. Any
cursor key movement which moves the
record pointer will also reset the
search string.
F1 - Display default keystroke handling.
F8 - Swap current column with the one on
the left.
F7 - Delete the current column from the
display.
F9 - Subtract one to the count of columns
on the left which are frozen. The
freeze value defaults to 0.
F10 - Add one to the count of columns
on the left which are frozen. The
freeze value defaults to 0.
If lAlite is False, the right and left arrow keys pan the
browse. If it is true, the cursor is moved one column.
The built in Get System allows the user to perform gets on the
entire browse or only on selected columns. The ability to define a
reader makes the browse totally configurable to your needs.
An append mode is included, but editing and appending to databases
is best performed by executing the task through ActionKeys.
Both vertical and horizontal scrollbars are available. If you
allow scrollbars, the horizontal one is displayed only if the
entire browse will not fit within the window.
Mouse Support:
The default mouse support varies according to the value of
lEditFlag.
When the browse is internally configured, two mouse hot spots may
be defined. The hot spots will cover the area occupied by the
scrollbars. If scrollbars are allowed, the mouse actions are:
Vertical Scroll Bar:
Direction Arrows:
Left Button: Up or Down one record.
Right Button: Page Up or Down.
Both Buttons: Top or Bottom of File.
Shaded Area: Move to Relative File
Position.
Horizontal Scroll Bar: Left Button
Shaded Area: Move to Relative Column
Position.
lEditFlag is TRUE:
Direction Arrows: Right or Left One
Column.
lEditFlag is FALSE:
Direction Arrows: Pan Right or Left.
Browse Table:
Right Button: Escape with no choice.
Left Button:
lEditFlag is TRUE:
Single Click: Move to Field.
Double Click: Edit Field.
lEditFlag is FALSE:
Single Click: Move to field.
Double Click: Select Record and
EXIT.
You may add your own mouse actions to the browse with
twBRHotSpot().
Arguments:
wT,wL
wB,wR - 'N' Screen coordinates at which to display the
browse. The defaults are:
0, 0, MAXROW(), MAXCOL()
aColumns - 'A' An array of column definitions to browse.
Each element in the column array passed to
twBRBrowse() MUST have at least TWO elements.
One is for the column header and the other for
the block used to display the data. Six other
elements are possible, but are not necessary.
One is the column width and the others define
and modify the get system in the browse.
The following is the array structure used to
pass columns to the browse:
Column Structure to Pass in aColumns:
AADD( aColumns, { cHead, bBlk, nWid, cFoot, ;
lEdit, cPic, bWhn, bVld, ;
bRdr, aClr, bClr, cCsep, ;
cHsep, cFsep })
Where:
1 - cHead - Browse Column Header
2 - bBlk - Browse Column Block for Data
3 - nWid - Optional Column Width
4 - cFoot - Browse Column Footer
5 - lEdit - Optional Logical to Allow Edits
6 - cPic - Optional Picture for Gets
7 - bWhn - Optional When Block for Gets
8 - bVld - Optional Valid Block for Gets
9 - bRdr - Optional Reader Block for Gets
10 - aClr - Browse Column DeFColor
11 - bClr - Browse Column Colorblock
12 - cCsep - Browse Column Separator to left
13 - cHsep - Browse Column Head Separator
14 - cFsep - Browse Column Foot Separator
The block definition should take the form of a
get-set block to allow the database field to be
updated, IF you allow editing. Such a block is
of the form:
{|x| IIF( x == NIL, cField, cField := x ) }
NOTE: If you are allowing direct edits on the
database in a network situation, the column block
MUST include the necessary record locking checks
to allow updating, eg.,
{|x| IIF( x == NIL, cField, ;
IIF( yLock( n ), cField := x, ;
dbUnlock() ), .F. )}
The Get Reader may be configured to allow cursor
movements after editing columns or to keep the
cursor out of columns.
NOTE: The get system will operate only if the
lEditFlag is set to true in the function call. If
it is, individual columns may be excluded from
editing by setting the fourth element, lEdit in
the column definition to False.
NOTE: If you use the append mode, all False
column definitions of lEdit become True.
Therefore, if appends are allowed, pictures,
whens, valids and readers may have to be assigned
to columns which are normally NOT editable. They
will be editable during appends.
NOTE: Append should be allowed only if there is
no scope imposed on the database with cTopKey and
bScopeBlock.
It is recommended that the edit, and especially
the append mode be reserved for 'down and dirty'
situations. The use of ActionKeys will allow you
to process database edits and appends much more
satisfactorily.
cTitle - 'C' Optional Title for the browse. See also bPreRun.
cTopKey - 'C' First index key for scoped browses. The default
is the first record in the key.
bScopeBlock - 'B' Code block to evaluate in order to determine if
a record is within the scope, eg.,
bScopeBlock := {|x| IIF( x=NIL,
LEFT( Windemo->CodeShort:, 1 ) == cTopKey,
LEFT( x, 1 ) == cTopKey )}
The bScopeBlock is best set up as a get/set
block with exact matching.
The default scope is all records.
lEditFlag - 'L' Logical to allow editing of fields. If you are
working in a network environment it is best to
edit records through the use of ActionKey
procedures, but you may include your network
file or record locking functions in the
individual column definitions or by replacing
the default keystroke handling where necessary
by passing ActionKeys to override the defaults.
The default is .F.
aActionKeys - 'A' An array of keys and code blocks to be executed
during the browse.
ActionKeys provide a means to pass executable
code to a browse. The information is passed in
an array where each element is a two element
array:
AADD( aActionKeys, { nKey, bBlock } )
Where: nKey - key number to assign
bBlock - code block to execute
If you are using SET Keys, you should save any
of them which might conflict with your
actionkeys before calling the browse, then
restore them on return.
wColor - 'C' Clipper colour string with which to configure
the browse. In order to be consistent with other
functions in TSDWIN, wColor must be passed as a
Clipper colour string. The minimum acceptable is
NIL, in which case the colour defaults to the
current SETCOLOR(). You must ensure that
SETCOLOR() is a full length colour string if you
do this.
The basic format for passing a colour is:
"x,x,,x,x"
TSDWIN uses the first two elements in the list
as the standard and enhanced colours for the
browse, and ALWAYS the last one for the
unselected colour, no matter how long your
colour string is. In a future release of TSDWIN,
all colours will be passed to all functions as
colorspecs.
You may want to pass more complicated colorspecs
if you choose to enhance your browse through the
column definitions.
wSType - 'N' TSDWIN Shadow type. The default is 0.
wFType - 'N' TSDWIN Frame type. The default is 1.
wFColor - 'C or A' If a character value is passed, it becomes
the frame colour for active and inactive
windows. If an array is passed, the first
element is used for active windows and the
second for inactive. If you are opening
other windows through ActionKeys, it is
recommended you use an array for this
parameter. wFColor defaults to the current
window colour.
lScBar - 'L' Logical for Scroll bar display. If this is set
to .T., a vertical bar is always displayed but a
horizontal bar is displayed only when the
columns in the browse will not fit into the
window. The default is .F.
lMsgs - 'L' Logical to display 'Wait' messages if the browse
is performing some type of time consuming
action. The default is .F.
lAlite - 'L' Logical to allow individual field highlighting.
If .T. the normal Clipper field highlighting is
followed. If .F., the highlight bar extends
across the entire window, including the column
separators. The default is .F., ie., NO field
highlighting.
nFreeze - 'N' The initial number of columns to freeze. The
default is 0.
lStabilize - 'L' The TBrowse Stabilize() method allows users to
break out of the stabilization process if a key
is pressed, thereby allowing the user faster
response on key presses. However, not all users
like the results when this is allowed. The
display will go blank in the browse window as
long as the user holds down a navigation key for
up or down movement. The lStabilize parameter
indicates whether or not carry out stabilization
to completion before processing the next key
press. The default is .F., indicating NOT TO
FINISH STABILIZING the browse as keys are
pressed. For large databases, the difference in
speed is very noticeable. The default is .F.
bPreRun - 'B' You may pass in a code block to execute before
the browse begins. For instance, the default
title colour in the browse is the standard text
colour. bPreRun allows you to change this by
leaving cTitle as NIL and creating:
bPreRun := {|| twTitle( "Title", YourColor" )}
bPostRun - 'B' This parameter acts like the PreRun block but is
executed after leaving the browse before the
browse window is popped if there is one.
nExitKey - 'N' The default exit keys are ESC and ENTER ( if
editing is disallowed ). You may wish to change
the behaviour of a browse with an ActionKey,
Therefore provision is made here to allow a
different key to provide an escape sequence.
Many users choose K_ALT_X to exit as it is used
in most CUA systems.
lBarOn - 'L' lBarOn defaults to .T. and indicates whether or
not the highlight bar is to be displayed when
AutoLite is set to off. If you set it to .F.,
you can use this browse to scan text files which
you have stored in an array.
aSeparators - 'A' An optional three element array of browse
separators. If this parameter is passed, it must
take the form:
{ HeadSep, ColSep, FootSep }
Column definitions may be used to override this
parameter.
lOKAppend - 'L' Logical to allow appends to the database. This
parameter, if TRUE, allows appending similar to
DBU. You must do the append at the end of the
browse. It is suggested that you use an
ActionKey for editing and appending to a
database. You have much better control that way.
lSound - 'L' Logical to allow a tone at HitBottom and HitTop.
lWindow - 'L' lWindow indicates whether you want the function
to open a window in which to display the browse.
You may wish to create a browse in part of a
window. lWindow allows you to do this. If
lWindow is set to .F., no window is displayed
and the browse fills the entire coordinate area.
bBarColor - 'B' Optional code block for the highlight bar color.
This parameter allows you to define a highlight
bar colour dependent on a logical condition,
eg.,
LOCAL nBar1 := twVAttr( aBarColor[ 2 ] )
LOCAL nBar2 := twVAttr( aBarColor[ 5 ] )
bBarColor := ;
{|| IIF( Members->Active, nBar1, nBar2 ) })
aSrch - 'A' Five element array which defines the search key
handling. aSrch must have the structure:
aSrch := { Column number on which to search, ;
Optional colour for the highlight
bar search string display,;
Optional code block for search the
database,;
Optional mask for the search
display,;
Optional prefix to apply to the
search string for scoped browses. }
The element descriptions are:
1 - The column number is simply the member of
aColumns which contains your index key.
2 - The current search string will be
highlighted within the highlight bar for the
browse. You may specify a colour or use the
default.
3 - The code block uses the current search
string as a parameter. Therefore it must be
of a form to properly locate keys in the
index. The default is to apply UPPER() to
the search string. You may make adjustments
for the method you used to create your
index.
4 - A mask for the display to compensate for
differences in the index key and the
displayed values. For instance, if you store
phone numbers as:
4166285086 in the file.
Then you use:
TRANSFORM( cPhone, ;
"@R (999) 999-9999" )
to display them. The mask would be:
"X XX X "
(999) 999-9999
X's or any character can be used in
positions where displayed data is not the
actual information if the database.
5 - If you are operating a scoped browse, all
the displayed records have keys starting
with the same character sequence. You may
pass this sequence to the search mechanism
so the highlighting will match the display.
For instance, if you are indexed on phone
number and scope to all records in the 416
exchange, your search prefix would be:
"416"
If aSrch is not passed, the default search
mechanism is:
1 - Search on column 1 of the browse.
2 - Clipper unselected colour.
3 - {|c| UPPER( c ) }
4 - SPACE( LEN( &(INDEXKEY())))
5 - Empty string.
You can turn off searching by passing .F. in place
of aSrch.
Return:
RECNO() or Zero for no choice. If you require another type of
return, you can get it with bPostRun.
See Also:
twBRBrowse
twBRHotSpot()
twBRMouseLine()
twBRGetBrowse()
This page created by ng2html v1.05, the Norton guide to HTML conversion utility.
Written by Dave Pearson